6.04. Руководство оператора по ГОСТ 19.505-79

В РАЗРАБОТКЕНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНО

Руководителю Аналитику Техническому писателю

Руководство оператора

ГОСТ

Основано на ГОСТ 19.505-79.

1. Введение в стандарт

ГОСТ 19.505–79 — советский государственный стандарт, входящий в Единую систему программной документации (ЕСПД), утверждённый постановлением Госстандарта СССР № 74 от 12 января 1979 г., с введением с 1 января 1980 г. Стандарт полностью соответствует международному/межгосударственному СТ СЭВ 2096–80.

1.1. Назначение документа «Руководство оператора»

«Руководство оператора» — нормативно-технический документ, предназначенный для лиц, непосредственно управляющих программой в процессе её эксплуатации (операторов, сисадминов, дежурных инженеров). Его цель — обеспечить корректный и безопасный запуск, управление, мониторинг и завершение работы программы в реальных условиях эксплуатации.

⚠️ Примечание: Термин «оператор» в контексте стандарта — не обязательно оператор ЭВМ (в узком смысле), а любой пользователь с правами управления жизненным циклом программы: запуск, пауза, останов, перезапуск, обработка ошибок.

1.2. Область применения

Стандарт применяется при разработке программного обеспечения:

• для государственных и оборонных заказчиков (в т.ч. в рамках ГОСТ ЕСПД — 19.101–77, 19.105–78 и др.);
• в проектах, регулируемых договорами, требующими соблюдения нормативной документации;
• в образовательных и методических целях — как эталон структуры эксплуатационной документации.

Хотя ГОСТ имеет статус «не действующий» в РФ (аннулирован в 2002 г.), его требования остаются практически востребованными:

• в legacy-проектах;
• в интеграционных решениях с государственными информационными системами (ГИС, ЕГАИС, ЕИС, ЕСИА и др.);
• в методиках разработки технической документации (в т.ч. в университетских курсах и корпоративных стандартах).

1.3. Нормативные ссылки и требования к оформлению

Согласно п. 1.1 стандарта:

«Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105–78».

ГОСТ 19.105–78 регламентирует:

• общий состав программной документации;
• структуру программного документа (титульный лист → лист регистрации изменений → аннотация → содержание → основное содержание → приложения → список использованных источников);
• правила нумерации разделов и подразделов (десятичная система);
• обязательное наличие информационной части (аннотация + содержание).

Таким образом, «Руководство оператора» — не свободный технический FAQ, а формализованный документ, подчинённый строгой структуре и метаданным.

---

2. Структура документа по ГОСТ 19.505–79

Стандарт устанавливает четыре обязательных раздела (п. 1.2):

№	Раздел	Обязательность	Краткое содержание
1	Назначение программы	✅ Обязательный	Функциональное описание, контекст применения, границы ответственности ПО.
2	Условия выполнения программы	✅ Обязательный	Требования к аппаратному и программному окружению, внешним зависимостям, конфигурации.
3	Выполнение программы	✅ Обязательный	Инструкции по подготовке, запуску, управлению, завершению. Форматы команд, ответы системы.
4	Сообщения оператору	✅ Обязательный	Перечень и расшифровка диагностических, информационных и аварийных сообщений.

2.1. Гибкость структуры

ГОСТ допускает (п. 1.2, 2.5, 2.6):

• объединение разделов (напр., «Условия выполнения» + «Выполнение» в единый «Подготовка и запуск»);
• введение дополнительных разделов («Аварийные процедуры», «Журналирование», «Мониторинг ресурсов»);
• иллюстрирование примерами, таблицами, схемами;
• вынесение вспомогательных материалов в приложения (лог-файлы, примеры конфигов, коды возврата, скриншоты интерфейсов CLI/GUI).

🔶 Пример допустимых дополнительных разделов:

• Работа с резервными копиями
• Диагностика производительности
• Интеграция с внешними системами
• Политики безопасности при эксплуатации

---

3. Пошаговое руководство по составлению «Руководства оператора»

Ниже — методически выстроенная последовательность действий для технического писателя или инженера-документалиста. Последовательность учитывает требования ГОСТ 19.505–79 и практику современной технической документации (включая DevOps- и SRE-подходы).

✅ Принцип: «Руководство оператора» — не описание кода, а инструкция по управлению состоянием системы в реальном времени.

Шаг 1. Подготовка метаданных и каркаса

1. Определите идентификатор и наименование программы
   Используйте официальное название и версию (согласно ГОСТ 19.101–77):

   Программа: «X-Engine» (версия 3.2.1, сборка 20251028.1)
   Код проекта: XEN-OPS-321
   Разработчик: ООО «IT Universe Labs»

2. Создайте базовую структуру документа (в соответствии с ГОСТ 19.105–78):

   • Титульный лист
   • Лист регистрации изменений
   • Аннотация (не более 250 слов)
   • Содержание (с нумерацией разделов по ГОСТ)
   • Основные разделы (по 19.505–79)
   • Приложения (если есть)

📌 Аннотация должна отражать:

• цели и задачи программы,
• класс решаемых задач,
• основную аудиторию операторов,
• особенности эксплуатации (непрерывный режим, пакетная обработка и т.п.).

---

Шаг 2. Наполнение обязательных разделов

2.1. Раздел 1. «Назначение программы»

Что писать:

• Функциональное назначение (не «что делает код», а «что решает для пользователя»).
• Контекст применения: автономный режим, серверный процесс, микросервис, batch-задача и т.п.
• Внешние взаимодействия (API вход/выход, файловые интерфейсы, очереди, БД).
• Границы ответственности: что входит в зону управления оператора, что — нет.

Что НЕ писать:

• Архитектурные диаграммы (вынести в Описание программы по ГОСТ 19.104–78).
• Исходный код или алгоритмы (это — Программа и методика испытаний, ГОСТ 19.301–79).
• Маркетинговые формулировки («революционный», «уникальный» и т.п.).

🔍 Проверка качества:
После прочтения раздела 1 оператор должен однозначно понять:
«Можно ли мою задачу решить этим ПО? Кто ещё участвует в процессе? Что я должен контролировать?»

2.2. Раздел 2. «Условия выполнения программы»

Обязательная информация:

• Требования к аппаратному обеспечению (мин./макс.):
  • CPU (ядра, архитектура: x86_64/aarch64)
  • RAM (мин., рекоменд., при пиковой нагрузке)
  • HDD/SSD (объём, IOPS, тип файловой системы)
• Требования к программному обеспечению:
  • ОС (в т.ч. дистрибутивы Linux, версии Windows Server)
  • Зависимости (runtime: .NET 8.0, OpenJDK 17, Python 3.11+; контейнер: Docker ≥24.0)
  • Сетевые требования (порт, протокол, TLS ≥1.3, DNS-резолвер)
  • Внешние сервисы (БД PostgreSQL ≥14, Kafka ≥3.5, внешний LDAP)

⚠️ Важно: указывать конкретные версии, а не «любая актуальная».
Пример недопустимой формулировки:
❌ «Требуется современная СУБД»
✅ «Требуется PostgreSQL 14.7–16.3 с расширением pg_cron. Подключение по TCP/IP (порт 5432, sslmode=require)»

Дополнительно рекомендуется:

• Таблицы совместимости (например, matrix OS × runtime);
• Диаграмма зависимостей (в приложении);
• Проверочные команды («быстрая диагностика окружения»).

Пример блока кода для проверки:

# Проверка минимального окружения для X-Engine
[ $(uname -s) = "Linux" ] || { echo "ОС: только Linux"; exit 1; }
[ $(getconf LONG_BIT) -eq 64 ] || { echo "Требуется 64-битная ОС"; exit 1; }
command -v java >/dev/null || { echo "Отсутствует Java"; exit 1; }
java -version 2>&1 | grep -q '17\|21' || { echo "Требуется OpenJDK 17 или 21"; exit 1; }

2.3. Раздел 3. «Выполнение программы»

Здесь — ядро документа. Структурируйте как цепочку состояний:

Этап	Подэтапы	Что указать
Подготовка	— Установка (если не отдельный документ) — Настройка (конфигурационные файлы, переменные окружения) — Предзапускная проверка (health-check)	Примеры config.yaml, env.example, схемы валидации
Запуск	— Интерактивный/фоновый режим — Параметры командной строки — Системные службы (systemd, launchd) — Контейнерный запуск (docker run, podman)	Точная сигнатура CLI: `xengine start [--mode=batch
Управление	— Команды runtime (pause/resume/shutdown) — Методы IPC (REST API /control, SIGUSR1, сокет) — Интерфейс CLI/REPL/веб-панель	Таблица команд с: синтаксисом, уровнем доступа, side-effect-ами
Завершение	— Штатное завершение (SIGTERM + graceful shutdown) — Аварийная остановка (SIGKILL) — Проверка корректного завершения (код возврата, логи)	Коды возврата: 0 — OK, 1 — ошибка конфигурации, 2 — timeout, 128+ — сигнал

📌 Включайте не только «как», но и «почему»:
«Параметр --grace-period=30s задаёт время, в течение которого система завершает обработку текущих задач перед закрытием соединений. Уменьшение значения ниже 10 с может привести к потере данных в режиме stream».

2.4. Раздел 4. «Сообщения оператору»

Структурируйте как реестр событий, отсортированный по критичности:

Уровень	Код	Текст сообщения	Причина	Действия оператора
INFO	XEN-1001	Engine started in batch mode, job queue length: 0	Штатный запуск	Наблюдать
WARN	XEN-2017	Config file /etc/xengine.yaml is world-readable	Нарушение security policy	Исправить права: chmod 640 /etc/xengine.yaml
ERROR	XEN-3022	Connection to PostgreSQL failed: timeout after 5000ms	Недоступен БД-хост	Проверить сеть, pg_isready -h db, повторить через 30 с
FATAL	XEN-4099	Required module 'crypto' not loaded (JCE not found)	Отсутствует Java Cryptography Extension	Установить JCE Unlimited Strength Policy или использовать OpenJDK ≥17

✅ Обязательно укажите:

• формат лог-сообщения (например: [TIMESTAMP][LEVEL][PID][THREAD] CODE: message);
• пути к лог-файлам по умолчанию (/var/log/xengine/main.log, journalctl -u xengine);
• методы фильтрации (grep -E 'XEN-[34].*' main.log).

---

4. Типичные ошибки и как их избежать

№	Ошибка	Последствия	Рекомендация
1	Описание для разработчика, а не оператора	Оператор не может понять, что делать, только почему так.	Пишите от лица оператора: «Выполните…», «Проверьте…», «Если видите X — сделайте Y».
2	Отсутствие конкретики в параметрах	Неопределённость → ошибки конфигурации.	Всегда указывайте: тип, единицы измерения, диапазон, значение по умолчанию, пример. Пример: --batch-size=100 (int, 1–10000, default=100)
3	Нет кодов возврата или сообщений об ошибках	Затруднена диагностика, необходимость читать исходники.	Выведите полный перечень exit-codes и сообщений в таблице. Ссылайте в логах на код (XEN-XXXX).
4	Объединение с «Руководством пользователя»	Путаница: пользователь ≠ оператор.	Чётко разделяйте: РО — для управления процессом, РП — для работы с функционалом.
5	Отсутствие примеров команд	Теория без практики → медленный onboarding.	Для каждого режима — один полный пример: xengine start --mode=stream --config=/etc/xengine.yaml --log-level=debug
6	Не указаны права доступа	Ошибки запуска от root vs xengine user.	Добавьте раздел «Требования к учётной записи»: UID/GID, группы, capabilities (CAP_NET_BIND_SERVICE).

💡 Правило «3-х вопросов» для проверки:
Любой пункт в РО должен отвечать на:

1. Что я должен сделать?
2. Как я пойму, что сделал правильно?
3. Что делать, если пошло не так?

---

5. Пример: фрагмент «Руководства оператора» для вымышленной системы X-Engine

Система X-Engine — модуль обработки потоковых данных в режиме near real-time.
Приём: JSON по HTTP/2 или Kafka. Обработка: агрегация, фильтрация, обогащение. Выдача: в ClickHouse и S3.
Режимы: batch (пакетный), stream (потоковый), replay (повтор воспроизведения логов).

5.1. Назначение программы

Программа xengine предназначена для выполнения потоковой обработки структурированных событий в распределённой среде. Основные функции:

• Приём событий через HTTP-эндпоинт /ingest (POST, JSON array) или потребление из Kafka (топик events.raw);
• Применение правил обработки из rules.d/*.yaml;
• Формирование агрегатов (минутные/часовые окна);
• Запись результатов в ClickHouse (events.enriched) и резервную копию — в S3 (s3://x-bucket/archive/).

Границы ответственности оператора:

• Обеспечение доступности xengine, Kafka, ClickHouse, S3;
• Мониторинг задержек обработки (lag);
• Реакция на аварийные остановки и ошибки записи;
• Не входят в зону ответственности: написание правил обработки, изменение схемы БД, развитие API.

---

5.2. Условия выполнения программы

Аппаратные требования

Режим	CPU (ядра)	RAM	Диск	Сеть
batch (до 10 тыс. эв/с)	4	8 ГБ	50 ГБ SSD (для temp)	100 Мбит/с
stream (до 100 тыс. эв/с)	16	32 ГБ	200 ГБ NVMe + 1 ТБ HDD	1 Гбит/с, <1 мс latency

Программные требования

• ОС: Ubuntu 22.04 LTS / RHEL 9 / AlmaLinux 9 (x86_64)
• Java: OpenJDK 17 или 21 (Temurin, Azul Zulu)
• Доступ к:
  • Kafka 3.5+ (bootstrap.servers, SASL/SCRAM)
  • ClickHouse 23.8+ (HTTP interface, user xengine, роль ingest)
  • S3-совместимое хранилище (AWS S3, MinIO — endpoint, access/secret key)
• Права: пользователь xengine, группа xengine; CAP_NET_BIND_SERVICE (для порта 8080)

Проверка окружения (скрипт /opt/xengine/bin/env-check.sh)

#!/bin/bash
set -euo pipefail

echo "🔍 X-Engine Environment Checker (v1.2)"
echo "OS: $(lsb_release -ds 2>/dev/null || cat /etc/os-release | grep PRETTY_NAME)"
echo "Java: $(java -version 2>&1 | head -1)"

# Проверка подключения к Kafka
echo -n "Kafka test: "
timeout 5 kafka-broker-api-versions --bootstrap-server "$KAFKA_BOOTSTRAP" &>/dev/null \
  && echo "✅ OK" || echo "❌ FAIL"

# Проверка ClickHouse
echo -n "ClickHouse test: "
curl -sf -u "$CH_USER:$CH_PASS" "$CH_URL/?" -d 'SELECT 1' &>/dev/null \
  && echo "✅ OK" || echo "❌ FAIL"

---

5.3. Выполнение программы

Запуск в режиме systemd

# /etc/systemd/system/xengine.service
[Unit]
Description=X-Engine Stream Processor
After=network.target kafka.service

[Service]
Type=simple
User=xengine
Group=xengine
ExecStart=/opt/xengine/bin/xengine start \
  --mode=stream \
  --config=/etc/xengine/config.yaml \
  --log-level=info
Restart=on-failure
RestartSec=10

# Важно: graceful shutdown за 30 с
TimeoutStopSec=30
KillSignal=SIGTERM

Команды управления:

sudo systemctl start xengine      # Запуск
sudo systemctl status xengine     # Состояние + последние логи
sudo systemctl reload xengine     # Перезагрузка конфига (без остановки)
sudo systemctl stop xengine       # Штатная остановка (ожидание завершения задач)
kill -SIGUSR2 $(pgrep xengine)   # Принудительный rotation логов

CLI-команды runtime (в REPL-режиме xengine shell)

Команда	Описание	Пример
status	Текущее состояние движка	> status → {mode: stream, uptime: 2h13m, lag: 1.2s}
pause processing	Приостановить обработку (буферизация продолжается)	> pause processing
resume	Возобновить	> resume
stop --force	Аварийное завершение (без сохранения состояния)	> stop --force
config reload	Перечитать config.yaml без перезапуска	> config reload

---

5.4. Сообщения оператору

Формат лога:
[2025-11-11T14:23:08.712Z][WARN][12345][main] XEN-2005: Rule 'fraud-detect-v3' took 1250ms (>1000ms threshold)

Код	Уровень	Текст	Причина	Действия
XEN-2005	WARN	Rule '{name}' took {ms}ms (>1000ms threshold)	Медленное правило	Проверить сложность условия, профилировать через xengine profile --rule={name}
XEN-3011	ERROR	Failed to write batch to ClickHouse: Code: 241. DB::Exception: Memory limit exceeded	Переполнение памяти в CH	Увеличить max_memory_usage в users.xml, уменьшить batch.size
XEN-4000	FATAL	Required Kafka topic '{topic}' does not exist and auto.create.topics.enable=false	Отсутствует топик	Создать топик вручную: kafka-topics --create --topic events.raw --partitions 12 --replication-factor 3

📌 Все сообщения логируются в journald и (при log.file.enabled=true) в /var/log/xengine/engine.log с ротацией через logrotate.

---

6. Чек-лист: «Готово ли Руководство оператора?»

Проверьте соответствие минимуму ГОСТ и практике:

№	Пункт	Выполнено? ✅/❌
1	Есть информационная часть (аннотация + содержание)
2	Все 4 обязательных раздела присутствуют
3	В разделе 1 указаны границы ответственности оператора
4	В разделе 2 — конкретные версии ПО/ОС, а не «рекомендованные»
5	В разделе 3 — точные команды запуска/останова + примеры
6	В разделе 3 — указаны коды возврата и их значения
7	В разделе 4 — все сообщения снабжены кодами (XEN-XXXX)
8	Для каждого сообщения ERROR/FATAL — алгоритм действий
9	Есть проверочные скрипты/команды диагностики
10	Есть приложения: примеры конфигов, схемы логов, таблица совместимости
11	Нет маркетинга, субъективных оценок, «воды»
12	Документ прошёл ревью с участием SRE/администратора

📥 Рекомендация: автоматизируйте валидацию через CI:

• проверка наличия XEN-\d{4} в руководство.md;
• проверка синтаксиса примеров bash через shellcheck;
• валидация config.yaml по OpenAPI-схеме.

---